home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Amiga Format CD 38
/
Amiga Format CD38 (1999-03-15)(Future Publishing)(GB)(Track 1 of 3)[!][issue 1999-04].iso
/
-in_the_mag-
/
reader_requests
/
dice_v3.15
/
doc
/
dice_debugger.doc
< prev
next >
Wrap
Text File
|
1999-01-26
|
33KB
|
722 lines
Dice/DD Dice/DD
Dice Debugger (DD) User's Manual
OVERVIEW
DD is a debugger designed exclusively for the DICE compiler environment.
In previous versions of DICE, all debugging had to be done with assembly
language debuggers or by inserting printf() calls in the code. This is
no longer the case! DD takes advantage of many old and many new features
in the DICE compiler to provide you with the ability to debug on the source
level. DD is both command-line and mouse driven.
DD allows you to examine your program in a variety of display modes and
using as many windows as you desire. DD also features ARexx support, the
ability to replace any of the builtin commands with an Arexx program,
and user-definable menus with amiga-key equivalents for the commands of
your choice. Its point-and-click input capabilities allow you to build
complex command lines by almost exclusively using the mouse.
DD is designed to be OS friendly under OS versions 1.3 and 2.0 (and up).
You may DD as many programs at a time as you like, limited only by the
memory in your machine. In fact, DD is so OS friendly, it is one of the
only debuggers that can actually be used to debug itself! To further
enhance the usefulness of DD, full source code (written in DICE 'C'
and A68K assembler) will be made available - you can add new commands
and features that you need to solve your particular debugging problems.
DICE FEATURES
The DICE features that DD specifically takes advantage of are important
to consider when writing your programs. The more you take advantage of
these great features in DICE, the better DD is able to do its job, too.
First and foremost, the DICE compiler now supports level 1 DEBUG hunks,
as does the SAS compiler and many available assemblers. In order to
enable source-level debugging capabilities of DD, you need to compile
with the -d1 option to generate these hunks. You can then use DICE
or any other debugger that supports the -d1 hunk format to do source
level debugging.
The DICE compiler also generates the standard Amiga SYMBOL hunks. These
are used by DD to provide you with symbolic debugging capability. When
these symbols are found in the executable by DD, you will be able to
use your symbolic names to reference subroutines, variables, and so on.
To cause DICE to generate the symbol hunks, you must use the -s option
when compiling.
Lastly, DD will cause the program being debugged to call exit() under
various circumstances. If you decide to quit DD while partway debugging
through a program, your program will immediately exit(). You should take
advantage of this to have your program clean up any resources it used
during the debugging session (close your windows, free memory allocated,
etc.).
DICE supports the ANSI atexit() function, which allows you to specify
a subroutine to be executed at exit() time. You should use the atexit()
function to specify your cleanup routine. ADDitionally, DICE supports
the __autoexit keyword, which allows you to declare subroutines that
are to be executed at exit() time as well. Use either method, or a
combination of both, and DD will help you to minimize the number
of reboots you will have to do when debugging those difficult bugs.
THEORY OF OPERATION
A brief discussion of how DD is implemented will help you to understand
the capabilities of the debugger more fully.
DD has its own custom LoadSeg() routine that is used to load the executable
from disk. The entire executable is loaded into contiguous memory, and memory
is allocated for your program's hunks as suggested by the CBM documentation.
When your program is RESET (see the reset command below), your program's
hunks are initialized from the originally loaded and relocations then performed.
This allows you to reset your debugging session and start over without quitting
and reloading all over again. The symbolic and debugging information found
in the original file are kept track of in the original file memory, to conserve
memory.
DD actually shares its process with the program being debugged. This is done
in a similar fashion to the Exec Signal Exceptions. The main difference is that
DD uses two stacks, one for the program being debugged and one for the debugger
itself. This is to eliminate the need for your program to have enough extra
stack to support the debugger, too. Only a single signal bit (shared among the
display windows) and the TC_TrapCode pointer of your Task structure will be
seen by your program while it is being debugged. Otherwise, DD is completely
invisible to the program and it will behave as if it were run from the CLI alone.
While debugging, your process will be in one of two states - debugger state or
program state. When in debugger state, the debugger has full control, responds
to your inputs, etc. When in program state, your program is in full control and
will run until it exits or until you hit a breakpoint or other stoppage (guru)
of your program. The debugger is careful NOT to do DOS calls which might cause
DOS to be entered twice - DOS is not reentrant...
GETTING STARTED
The DD executable should be in your DCC:bin directory along with your other
DICE executables. DCC:bin should also be on your path. Note that DD is
not a PURE program so you can not make it resident! Now you can go to
any directory you have a DICE compiled program and debug it. Remember to
compile with -s -d1 to get full debugging capability.
To launch the debugger, just type:
1> DD myprog parm parm parm ...
Where myprog is the name of your program (to be debugged) and parm parm parm
is the typical CLI arguments that you would give to your program. DD will
open a console window for you to enter commands.
If you are debugging a 'C' program (DD works for assembly programs, too), DD
will automaticall set a breakpoint at _main() or @main(), which is the main()
routine of your program. You can quit your debugging session at any time by
hitting ^C while the debugger is active, and DD will exit after causing your
program to exit(20).
DD'S WINDOWS
You initially start DD and have a single console window to control the debugger
from. The top few lines of the window are used to display the CPU registers of the
current state of your program. All the standard 68000 Data and ADDress Registers
are displayed, as well as the PC, and SR registers. The individual bits of the
condition codes (CCR) are displayed to the right of the SR. Also, the program's
state is displayed. Many states are possible, but typically your program will be
stepped, steppedover, at a breakpoint, exited, or crashed (CPU exception). As
you maneuver through your program with the debugger, values that change in these
lines will be highlighted - a visual clue to what's changing.
If you use the watchpoint features of DD, your watchpoint display will appear
below the register display. Below this is a general purpose scrollable display window which
DD uses to display various information that you ask it to. To change the information
in the display area, you change the Display Mode to that of your choice. Initially,
the display area is in MIXED MODE, where your program is shown to you as lines of
source code with disassembly intermixed. When you start DD, your MIXED MODE
display will show you where the PC register points. The lines of source and
disassembly that represent the current PC location will be highlighted - most likely
_main or @main.
Below the general purpose display is the Status: line, where DD will display
its various status and error messages. Initially, this line says:
Status: Ready for command.
Below the status line is the command line itself. As you type in your commands,
they will be displayed on the command line. The left side of the command line
is your prompt, which consists of some funny looking sequence of characters
(described in the mouse input section) and the name of the source file that
the PC is in. It is always good to know what file your bug is in...
And finally, below the command line are two lines reserved for display of the
current function key bindings. By default, these are bound to some very common
commands that you would otherwise have to type.
DD supports multiple windows - but all share the same command line. You use
the "open" command to open a new console window. You may enter commands into
any window. Commands that change a window's mode or display position will affect
the window you type into.
MOUSE INTERFACE
The right mouse button is used, as normal, to operate the Intuition Menus that
are bound to the window. The left mouse button is a select button and operates
differently, depending on where you click. Clicking on text in the window
generally causes the word you clicked on to be entered onto the command line
automatically for you. That funny character string on the left of the prompt
is there so you can click to generate those characters. Clicking to the
right of the command line is like hitting return to execute the command.
You can click in any combination of windows to build your command lines.
COMMAND SUMMARY
Below is the command summary as found in the help command (help mode display).
NAME
again - repeat last command
alias - replace command with arexx script
bp {expr} - set breakpoint at expression
bp ALL - set all breakpoints in table
breakpoints - display breakpoint table
bytes {expr} - display bytes {at expression}
changewindow - move/size current window
clear expr - clear breakpoint at expression
clear ALL - clear all breakpoints in table
close - close a display
devs - display Exec Device List
dism {expr} - change to dism mode {at expression}
dosbase - intelligent display of DOSBase struct
down - move display down one line
eval {expr} - evaluate an expression
execbase - display ExecBase (SysBase)
fkey - set function key definition
go {expr...} - set {expr...} temp breakpoints & go
help - online help
hunks - change to hunks mode
info - display ThisTask info
intrs - display Exec Intrs List
jump {name} - jump to public screen
libs - display Exec Libs List
longs {expr} - display longs {at expression}
mbar - add menu bar
mend - add menu end mark
memlist - display Exec Mem List
mitem - add menu item
mixed {expr} - change to mixed mode {at expression}
menus - activate a new set of user menus
msub - add a sub menu item
mtitle - add menu title
offsets - toggle display address/offsets
open {type} - open a new display
over {range} - stepover one instruction or range
pagedown - move display down one page
pageup - move display up one page
rendlist - end the arexx list
rgetbyte {expr} - get bytes at {expr}
rgetcom - get command line input
rgetdism {expr} - get the dissembled line
rgeteval {expr} - evaluate the expression
rgetinfo {expr} - get the program nam
rgetline {expr} - return the source/mixed line
rgetlong {expr} - get longs at {expr}
rgetword {expr} - get words at {expr}
rgetpc - return the program counter
rputlist - add an item to the arexx list
rshowlist - show the arexx list
rstartlist - start the arexx list
rx rexx-script - execute ARexx macro
saveprefs - save DD prefs to disk
set {addr} {val} - set address to val
ports - display Exec Ports List
process {expr} - display process {at expression}
resources - display Exec Resource List
quit - _exit(20) & quit DD
refresh - refresh the window
registers - toggle the register display
reset - _exit(20) & restart program
rstep - toggle library call auto stepover flag
source {expr} - change to source mode {at expression}
step - step program one instruction or range
symbols {expr} - display symbol {at expr}
symlist - display sorted symbol list
tasks - display Exec Task Lists
unalias - restore command with arexx script
up - move display up one line
watchbyte {expr} - set/clear (toggle) byte watchpoints
watchclear - clear all watchpoints
watchlong {expr} - set/clear (toggle) long watchpoints
watchword {expr} - set/clear (toggle) word watchpoints
words {expr} - display words {at expression}
EXPRESSIONS
The expression evaluator can handle most C style expressions, and can be used
on the command line to set breakpoints, display source, and so on.
KEYBINDINGS
The following keys are bound, as defaults, in DD:
upcursor = up
downcursor = down
shift upcursor = pageup
shift downcursor = pagedown
leftcursor = left
rightcursor = right
return = execute command
HELP = toggle to help display (help = help mode, help again = previous mode)
AREXX SUPPORT
DD is the base name of DD's ARexx port. The ARexx commands that are
supported by DD are identical to those that you type in at the command
line. DD also has the rexx command to allow you to run rexx scripts
as macros from inside DD. These rexx script files should have the
.DD extension, so you can identify which scripts are for DD.
The ALIAS command allows you to replace any of the built in commands
with an Arexx script of the same name (with an appended .dbug). DD looks
first in the current directory, then in dcc:rexx/ for the command.
UNALIAS cancels a previous alias. From within the ARexx script, the internal
command can be called by name. (as can all internal commands)
The results of an internal command called by an ARexx program are placed
in the ARexx result variable.
NOTE: Aliases are part of the DD preferences saved to disk, and automatically
loaded on starting DD.
The Rexx port name of the first port is DD.01 Subsequent ports are named
DD.02, DD.03, and so on.
COMMAND DESCRIPTIONS
AGAIN
This command repeats the last command entered. It is
occasionally useful when a complicated command was entered.
ALIAS
This command provides a limited alias function for all internal
commands. When an internal command is aliased, DD looks for an AREXX
program with the same name (with the .DD extension) and executes that
instead of the internal command. The internal command is still
available, however, by specifying the name within the ARexx program.
This allows you to, for instance, write a replacement pagedown command that
first sends a message to the AME editor, then calls the built in DD pagedown
command. To save the change, the saveprefs command must be used.
BP {expression}
The BP command sets a breakpoint. If the optional
{expression} is given, DD will set the breakpoint at that address.
The expression can also be a source line number (indicated by the
trailing period.) DD will look up the source line specified, and set
the breakpoint at the start of the code for that source line. If no
expression is given, DD sets the breakpoint at address in the Program
Counter. A line containing a breakpoint is underlined on the display.
The mouse can also be used to set (and unset) breakpoints. Just
doubleclick on the left (address) column of the display area, and the
breakpoint is set. (If you doubleclick on an already set breakpoint,
it will be unset). If there is no more room in the breakpoint table,
and there are unarmed breakpoints, one will be replaced by a newly
set breakpoint; otherwise the attempt to set a new breakpoint will
fail.
BP ALL
When a breakpoint is hit, it is automatically unset. However,
it is still in the breakpoint table, and can be rearmed. The bp all
commnd rearms all breakpoints in the table.
BREAKPOINTS
This command displays the table containing the current
breakpoint list, and current status. Breakpoints can be set and unset
directly on the table display itself.
BYTES {expression}
The bytes command changes the display mode of the current
window to the bytes display. The optional expression allows you to
specify the start of the byte display. (DD attempts to keep enforcer
happy; most illegal accesses are trapped). If no expression is
specified, the address of the display remains the same; just the mode
is changed.
CHANGEWINDOW
This command is used to move and size the curren DD window. It
only operates under AmigaaOS 2.0 or greater (so, why haven't you
upgraded yet ?). The command takes the two coordinates of the upper
left corner of the window, the width, and the height, and moves the
window there if possible.
CLEAR {expression}
This command clears the breakpoint at the expression. If no
expression is given, the breakpoint is cleared at the PC location.
The breakpoint is not removed from the breakpoint table, and may be
re-armed by the BP command.
CLEAR ALL
Clear all clears the entire breakpoint table.
CLOSE
This command closes the current display window. If the current
window is the only DD window open, DD exits.
DEVS
This command displays the current Exec Device List
DISM {expression}
The dism command changes the display mode of the current window
to the disassembly display. The optional expression allows you to
specify the start of the disassembly display. (DD attempts to keep
enforcer happy; most illegal accesses are trapped). If no expression
is specified, the address of the display remains the same; just the
mode is changed.
DOSBASE
This command displays the pulic fields of the AmigaDOS DOSBase
structure.
DOWN
This command is used to move the cursor down one line. New
informtion is displayed at the bottom of the display area if the
display scrolls. This command acts the same as pressing the cursor
down key.
EVAL {expression}
This command evaluates an expression, and prints the result to
the screen.
EXECBASE
This command displays the current contents of the public fields
of ExecBase.
FKEY num definition
This command is used to set one of the ten function key
definitions. The command takes the function key number (from 1 to 10)
and the definition string.
GO {expression}
The go command sets all the breakpoints in the breakpoint
table, and starts execution on the program being debugged. Execution
begins at the expression if provided; otherwise execution begins at
the address contained in the program counter (PC). The program runs
at full speed; the debugger does not regain control until either the
program exits, or the program encounters one of the breakpoints. If
more control over the execution is desired, you should use one of the
single step functions (step or over) instead.
HELP {command}
Provide short online help list
HUNKS
This command changes the current display to a table of the
hunks in the progra being debugged.
INFO
This command displays information on the current task, taken
from the task structure.
INTRS
The intrs command displays the Exec interrupt list.
JUMP {name}
The jump command is used to jump a DD window to another public
Intuition screen. With no argument, the jump command jumps the window
to the next public screen. If an argument is specified, the jump
command jumps the window to that public screen. If the screen does
not exist (or there is only one public screen, ie Workbench) nothing
happens.
LIBS
This command diplays the Exec library list.
LONGS {expression}
The longs command changes the display mode of the current
window to the longs display. The optional expression allows you to
specify the start of the longs display. (DD attempts to keep enforcer
happy; most illegal accesses are trapped). If no expression is
specified, the address of the display remains the same; just the mode
is changed.
MBAR slot
This command is used when setting up the programmable menu
system, to add a menubar at the specified slot. The slot can be a
positive integer (from 0 to 127) or -1 (which tells DD to append the
new menu bar to the existing menus) When this command is used, menus
are automatically turned off, and must be turned on with the menus
command.
MEND
This command is used when setting up the programmable menu
system, to add a menu end marker at the specified slot. The slot can
be a positive integer (from 0 to 127) or -1 , which tells DD to append
the new menu end marker to the existing menus. When this command is
used, menus are automatically turned off, and must be turned on with
the menus command.
MEMLIST
This command displays the current Exec memory lists
mitem slot label command shortcutkey
This command is used when setting up the programmable menu
system, to add a menu item at the specified slot. The slot can be a
positive integer (from 0 to 127) or -1 , which tells DD to append the
new menu item to the end of the existing menus. The label is what is
displayed in the menu. The command is what is executed when the menu
item is selected. The optional shortcut key is used to assign a Right
Amiga key shortcut to the function. When this command is used, menus
are automatically turned off, and must be turned on with the menus
command.
MIXED {expression}
The mixed command changes the display mode of the current
window to the mixed display. The optional expression allows you to
specify the start of the longs display. (DD attempts to keep enforcer
happy; most illegal accesses are trapped). If no expression is
specified, the address of the display remains the same; just the mode
is changed. The mixed mode display consists of the source for the
program being debugged (if available) interspersed with the
disassembled instructions that each source line compiles to.
MENUS
This command activates the DD menus.
MSUB slot label command shortcutkey
This command is used when setting up the programmable menu
system, to add a menu subitem at the specified slot. The slot can be a
positive integer (from 0 to 127) or -1 , which tells DD to append the
new menu subitem to the end of the existing menus. The label is what
is displayed in the menu. The command is what is executed when the
menu item is selected. The optional shortcut key is used to assign a
Right Amiga key shortcut to the function. When this command is used,
menus are automatically turned off, and must be turned on with the
menus command. Sub items are automatically attached to the nearest
previous menu item. DD does not support sub items under 1.3.
Instead, they are treated as menu items.
MTITLE slot label
This command is used when setting up the programmable menu
system, to add a menu title at the specified slot. The slot can be a
positive integer (from 0 to 127) or -1 (which tells DD to append the
new menu title to the existing menus) Each menu title must have at
least one menu item following it. The label is used as the menu
title. When this command is used, menus are automatically turned off,
and must be turned on with the menus command.
OFFSETS
This command toggles the display of addresses as either offsets
from a listed symbol name or plain hex addresses.
OPEN {type}
This command is used to open a new DD display. If no type is
specified, a new window is opened with the same display as the current
window. Otherwise, a display of the specified type is opened. The
displys are somewhat independent ... each can display a different
address, but share breakpoints, the registers, Rexx port name, etc.
OVER {range}
This command is used to single step the program under debug,
stepping over subroutines. The subroutine is executed, and control
returns to the debugger at the instruction immediately following.
The optional range parameter allows you to set up an address range
for execution. Control returns to the debugger if the program
under debug leaves the range.
PAGEDOWN
This command is used to move the cursor down one page. New
informtion is displayed at the bottom of the display area if the
display scrolls. This command acts the same as pressing the shifted cursor
down key.
PAGEUP
This command is used to move the cursor up one page. New
informtion is displayed at the top of the display area if the
display scrolls. This command acts the same as pressing the shifted cursor
up key.
RENDLIST
This command is used to signal completion of a buffer list creation
by an external ARexx program. DD allows external commands to create an
information list through its ARexx port. The list is then available for
display; DD handles scrolling, refresh of the list, and so on. This command
tells DD that the list is complete and ready for display.
RGETBYTE {expression}
This command is used to get one line of bytes at expression. If no
expression is provided, the bytes will be fetched from the location specified
by the PC. The bytes are returned in the ARexx RESULT variable.
RGETCOM
This command is used to get the command line. The command line
is returned in the ARexx RESULT variable.
RGETDISM {expr}
This command is used to get one line of disassembly at expression. If no
expression is provided, the disassembly will be fetched from the location
specified by the PC. The bytes are returned in the ARexx RESULT variable.
RGETEVAL {expr}
This command evaluates the expression, and passes it back in the
ARexx RESULT variable.
RGETINFO {expr}
This command is used to get the program name and current line number
of the expression. If no expression is provided, the information will be
fetched from the location specified by the PC. The results are returned in
the ARexx RESULT variable.
RGETLINE {expr}
This command is used to get one line of mixed display at expression.
If no expression is provided, the disassembly will be fetched from the location
specified by the PC. The lines are returned in the ARexx RESULT variable.
RGETLONG {expr}
This command is used to get one line of long words at expression. If no
expression is provided, the long words will be fetched from the location specified
by the PC. The bytes are returned in the ARexx RESULT variable.
RGETWORD {expr}
This command is used to get one line of words at expression. If no
expression is provided, the words will be fetched from the location specified
by the PC. The bytes are returned in the ARexx RESULT variable.
RGETPC
This command is used to get the value if the current Program
Counter (PC). The bytes are returned in the ARexx RESULT variable.
RPUTLIST
This command is used to add a line of text to the buffer list being
created by an external ARexx program. DD allows external commands to create an
information list through its ARexx port. The list is then available for
display; DD handles scrolling, refresh of the list, and so on. This command
gives a line for DD to add to the list.
RSHOWLIST
This command is used to display the external buffer list previously
created with the rputlist commands.
RSTARTLIST
This command is used to signal the start of creation of a buffer list
by an external ARexx program. DD allows external commands to create an
information list through its ARexx port. The list is then available for
display; DD handles scrolling, refresh of the list, and so on. This command
initializes the buffer list.
RX rexx-script
This command executes an external ARexx script file. DD will treat any
command given by the user which is not an internal command as an ARexx
command; the rx command is to execute scripts with the same name as
internal commands, or the same name as a symbol from the program under debug.
SAVEPREFS
This command saves the configuration file for DD to dcc:config/dd.config.
This file contains information on which commands are aliased, window position
information, etc.
SET {address} {value}
This command is used to set the address to the specified value. If the
value is not given, a 0 will be used. This command can also change the value
of the registers (A register is denoted by the trailing :, ie A0: or PC:).
PORTS
This command is used to display the Exec port list.
PROCESS {expression}
This command is used to display process information for the process
at {expression}. If no expression is given, the address contained in the
Program Counter will be used instead.
RESOURCES
This command is used to display the Exec resources list.
QUIT
This command calls the exit routine (_exit or @exit) of the program
under debug with a 20 in D0, then exits from the DD program.
REFRESH
Refresh the current window display.
REGISTERS
This command toggles the register display. Some windows contain the
register display by default (the mixed mode display, for instance). Others
do not (the source display). The registers command changes this for a
particular window. Once the registers command has been executed in a
window, the register display is on 'manual', and just obeys the register
command.
RESET
This command calls the exit routine (_exit or @exit) of the program
under debug with a 20 in D0, then restarts the it.
RSTEP - toggle library call auto stepover flag
This command toggles the auto stepover flag for libraries. If rstep
is on, then DD will automatically use OVER when asked to STEP into an
Amiga rom routine.
source {expression}
The source command changes the display mode of the current window
to the source display. The optional expression allows you to
specify the start of the source display. (DD attempts to keep
enforcer happy; most illegal accesses are trapped). If no expression
is specified, the address of the display remains the same; just the
mode is changed.
STEP
This command is used to single step the program under debug.
The optional range parameter allows you to set up an address range
for execution. Control returns to the debugger if the program
under debug leaves the range.
SYMBOLS {expression}
This command is used to display the symbol table for the program
under debug. Breakpoints can be set from this table. This table is
ordered by address.
SYMLIST
This command is used to display the symbol table for the program
under debug. This table is sorted.
TASKS
This command will display the Exec task list.
UNALIAS
This command removes a previously set alias. To save the change,
the saveprefs command must be used.
UP
This command is used to move the cursor up one line. New
informtion is displayed at the top of the display area if the
display scrolls. This command acts the same as pressing the cursor up key.
WATCHBYTE {expression} - set/clear (toggle) byte watchpoints
This command is used to see the values of bytes at the specified
expression. This command sets or clears a watchbyte. If there are any
watchbytes, the display is added to the current DD window; otherwise there is
no watchbyte display. The expression can be an address, or a symbol.
WATCHCLEAR - clear all watchpoints
This command removes all watchbytes, watchwords, and watchlongs.
WATCHLONG {expr} - set/clear (toggle) long watchpoints
This command is used to see the values of longss at the specified
expression. This command sets or clears a watchlong. If there are any
watchlongs, the display is added to the current DD window; otherwise there is
no watchlong display. The expression can be an address, or a symbol.
WATCHWORD {expr} - set/clear (toggle) word watchpoints
This command is used to see the values of words at the specified
expression. This command sets or clears a watchword. If there are any
watchwords, the display is added to the current DD window; otherwise there is
no watchword display. The expression can be an address, or a symbol.
WORDS {expression}
The dism command changes the display mode of the current window
to the word display. The optional expression allows you to
specify the start of the word display. (DD attempts to keep
enforcer happy; most illegal accesses are trapped). If no expression
is specified, the address of the display remains the same; just the
mode is changed.